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I. INTRODUCTION 

Pretty— printing is a fundamental debugging aid fcr LISP. 
List structure presented as an unformatted linear string is very 
difficult for a rerscn to understand. The purpore of pretty- 
printing is to clarify the structure of a LISP expression. The 
simplest class of pretty-printers accomplishes this ty the judicious 
insertion of spaces end carriage returns. Section II analyzes the 
computational complexity of such algorithms. [See section IV for 
suggestions for more sophisticated schemes vhich break the code into 
separate expressions.] The existence of algorithms vhich are only 
linearly more expensive than the standard LISP printing routines is 
demonstrated. Various extensions fcr adding remantic knowledge to 
the pretty-printer are then considered. Section III documents the 
pretty-print package currently available for MACLISP. Section IV 
suggests additional improvenents to be considered for the future. 

II. COMPUTATIONAL AKALYSIS 

A. THE BASIC TASK 

The LISP PRINT'ing primitives print expressions as strings. 
Their only concession to clarity is the insertion of a carriage 
return each t ice the right margin is reached. This results in code 
vhich is not very readable when longer than a single line. Indeed, 
the carriage returns can even be inserted directly into the middle 
of a word. [The LISP reader ignores carriage returns on input]. 
The following example is the definition of FACTORIAL PRIfiT'ed by 
LISP. The dots represent the left and right margins. 

# (rEFUN FACTORIAL (X) (CO* 
MD ((= X 0) 1) ((* (FACT 
ORIAL (1- X)) X))J) 

Let L be a list of the following form: 

(<FUliCTIC]l> <ARG(1J> <ARC(2)> ... <AEC(K)>) 

The objective of the pretty-printer is to present L in a fashion 
which emphasizes its procedural role- The "Ftandard format" for 
accomplishing this is aligning the argiunents one under the next. 



(<rui;cTia:> pretty-print arc(i)> 
<rREm-rniHT ARC(2)> 



•CFRfTTY-rRUJT ARC(N)>) 

Usinr this fcrmat, the FACTORIAL function toy.es en the fcllowinf, 
more understandable, appearance: 

"(DEFUH FACTORIAL 

!C0NII ((= X 0) 1) 

{(* (FACTORIAL (1- X)) 
xjj) ; 

• 

Itote that any format used by pretty-print must leave L re- 
readable by LISP. Hence, the following rtructure would be illegal: 

(<FUKCTI0H> <FRETTY-PRINT ARG(1)> <FREITY-PRIKT ARG(H/2 + 1)> 
<FRETTY-PRI1JT ARG(2)> <PRETTY-PRIi:T ARG(l.'/2 + 2)> 



<treity-frint arg(n/2)> <pretty-prirt arg(h)>) 

If the only problem which the pretty-printer faced was the 
insertion of extra spacer and carriage returns, the computational 
cost in excess of the standard LISP FRUIT would be negligible. The 
difficulty arises from the finite width of the pege. For 
sufficiently large s-expressions, every rublist cannot be printed in 
standard format. Instead, the less desirable miser format must be 
used. 

(<FUNCTIOH> 
<FRETTY-PRIKT ARG (1)> 



<PRFTTY-PRINT ARG (N)>) 

This format is minimal with respect to the indentation of the 
arguments* All arguments befin only one space over fron the opening 
parenthesis. 

Thore are rare instances of lists that cannot be pretty- 
printed even in miser format* If the depth of the list 
exceeds the width of the pa^e, indenting one for each level 



is impossible. See rurrcsticn A-3 ir section IV for a 
technique for h&ndlinp expressions of pre^t depth. 

The role of miser format is illustrated by our FACTORIAL 
examples. When first shown FRINTed, the rarevidth was 24 sjaces. 
However, the r^evidth was increased to 75 in order to demonstrate 
standard format. Without the extra width, it is impossible to use 
standard foroat on the list and all cf its sub-expresniors without 

exceeding the ripht-hand rcarpin. Hence, the pretty-printer is facer 1 
with the necessity to use miser format on noire sutv-exprersi ons if 

the entire list is to fit on the psipe. This prediction represents 
the tasic extra-cost above the standard LISP PRIKT which the pretty- 
printer requires- The following format for FACTORIAL ilustrates the 
cautious use of miser format until sufficient width becomes 
available to switch to standard form. 

# (DEFUN 
FACTORIAL 
(X) 
(COM) 

> X 0) 1) 

(FACTORIAL (1* X) 



f- 



E. FINITE tflDTO 

What, then, are the tasic corputatioral costs for pretty- 
printinp on a jape of finite width? If lists are described as 
trees, then the cost cf printing* is simply that of visitinp each tip 
of the tree in left-to-right order. The cost of pretty-printing 
will be analyzed with respect to this basic "tree traversal" 
overhead. Upon first arriving at any non-terminal node of the tree, 
the pretty-printer has no knowledfe of the size of the subtree 
tefinninf there. Hence, it cannct Imow whether there is sufficient 
space to use standard format. The pretty-printer must apply a 
prediction function to the subtree to estimate the width required to 
print it in standard fonrat. If that width is mere than is 
currently available, miser format must be used. The additional cost 
of pretty-printirf , then, is simply the cost of prediction. 

Cne criterion for judpinf different pretty-print algorithms 
is the number of times each ncde of the tree must be revisited. In 
these teres, a minimal alforithm would perform only two tree 
traversals - one to obtain prediction information and one to 
actually print the subtree." 

The following analysis will proceed St a oualit&tive level. 
The assumption will be that ]ist operations represent the ma^or 



cost, with numerical operations teinr chepp. The intention If to 
five the reader the flavor of this computational problem. However, 
to turn th se assertions into theorems" wculd reouire a mere formpl 
attack. For examyle, a precipe comparison of ttie cost of numerical 
versus list operations would he necessary. Otherwise, ore pass 
through the the tree could be used to Godelize it* Subsequent 
computation could then fce entirely numerical. 

Is a "minimal" two-traversal algorithm possible? The answer 
is yes* [This yes assumes that the number of lines reeded tc print 
the expression is ignored. The section en "finite length" considers 
this additional complexity.] One j^ss can t*> race to associate with 
each sublist the minimal width needed to print it in standard 
format* This information completely determines how the s-expression 
is printed. The pretty-printer uses the more economical miser 
format from the top down, until the available width exceeds the 
minimum needed to use standard format. At that point, the printer 
is assured of room to print all reraining sublists in standard 
format* This is the structure which was used to print FACTORIAL in 
the last example* 

A single prediction rass is sensible providing the cost of 
storing and accessing the minimum width computed for each piece of 
substructure is less than the cost of recomputing the number. 
Fortunately, this is the case* For example *. a hash table accessed 
ty a numerical computation on the pointer to the sublist takes fixed 
time, regardless of the size of the list structure. Of course, for 
sufficiently small list structures, the fixed cost of accessing and 
clearing a hash table will not be worthwhile. Put this is 
uninteresting mathematically. Indeed, even from a practical 
standpoint, the hash scheme is so fast that its overhead is not 
noticed en small lists. 

0- LINEAR PORMAT 

Analysis of the pretty-printing task was begun in reaction 
to the urinfermative use of "linear format" by the LISP primitives. 
However, when a subexpression can fit in the space remaining on the 
line, linear format is sensible* As ve shall see, even with this 
additional complexity, two tree traversals are sufficient. 

The prediction pass must now save two pieces of data - the 
linear width of the sub-expression as well as its mirimurc width* 
These two numbers can be computed on the same pars through the tree. 
The printing pass is extended in the obvious way. First preference 
is given to linear format if sufficient width is available. 
Otherwise, the algorithm is as before. 



E, FINITE IENCTH 

Th^re is an additional elemert of corrlexity in pretty- 
printing that has not yet been considered, Vnen LISP code let spread 
out over many lines cr, worse, many paper, it pppin tecores 
indecipherable- Hence, a pretty-print algorithm should alro attempt 
to format s-expressions in the least number of lines. To achieve 
the minimum number of lines, we rhall have to allow an increase in 
computational cost. Nevertheless, we will propose a scheme which 
still requires only two tree traversals and is therefore linear in 
the size of the tree. 

The predictor dercrihed above car compute the number of 
lines needed to print an exprer-sion in minimal width. The 
difficulty, however, is that there may be extra width available. 
This can allow the use of linear format to decrease the number of 
lines needed to print the expression. For example, for FACTORIAL, 
the pretty-printer always prints the second argument of "*" under 
the first* However, with sufficient width, a lire is saved by 
printing (* (FACTORIAL (1- X)) X) in linear format. 

* 

"(DEFUK FACTORIAL 
(X) 
(COKD ((= X 0) 1) 

((* (FACTORIAL (1- X)) X)))) 

• * 

For functions with many arguments such as (PLUS 123456 7), the 
use of linear format over standard format can mate a significant 
difference in the number of lines and, consequently, the 
readability. Thus, remembering a sirple datum corresponding to the 
number of lines needed to print a piven sub-expression in minimal 
width is not sufficient information. At first blush, it would 
appear necessary to reexamine each sufc-exprersion overy time the 
available width chanfes. 

E. IKE RECURSIVE RE^-FREDICTOR, A TOP-DOWN ALGORITHM 

Let us beg-in by examining approaches that do reexamine 
sublists many times. One obvious algorithm is tc consider all 
possible format choices at each node, computing the result inp number 
of lines required. Py brute search, this approach is guaranteed to 
find the sequence of formats that yields the minimum number of 
lines. However, the exponential cost is certainly prohibitive. A 

less powerful but less costly alternative is the RECURSIVE RE- 
PREDICTOR. 

The RECURSIVE RE-PRETICTCR works in the follcwinf way. Upon 
arriving at a piven rode, the algorithm knows N, the reraininp 



available width- Lirear ferae t is urod if N is sufficiently larfe. 
Otherwise, it estimates how many lines it would take to print the 
arguments 

in width (PI — 1) corresponding to the use of miser format 
and in width (N - <iinear width of the function>) correspondinr 
to standard format. 

The estimate is made by fuesring that all sutlists are printed in 
the following way: 

linear format if sufficient width; 
else standard fenrat. 

Ihis scheme is not guaranteed to find the sequence of format choices 
that results in the ininicum number of lines* It doer not consider 
all possible sequences. When insufficent space occurs, it print? 
the toplevel expression in miser format. It ignores the possibility 
of printing the toplevel expression in standard format while 
printing the sublists in miser form. 

Computationally, the RECURSIVE RF-PREDICTOR can reexamine a 

S'ven subtree many times. Thus, the cost is still exponential in 
e worst case. Nevertheless, for various reasons, this approach is 
possible: 

1. Lirts beginning with non— atomic elements such as LAMBDA 
expressions can always be printed in miser format. This 
avoids prediction costs for these sublists. 

2. There is no longer any point to remembering the minimum 
width needed for standard format. Since the rredictor must 
reexamine each sublist for the number of lines, it can at 
the same time check that the list fits in the given width. 

3- A hash table can still used to remember the linear width. 

4. Empirically, iruch LISP code is broad tut not deep. 
FROG's are typical examples. After predicting and printing 
the first level cr two, it is often the case that the 
remaining elements alirost all fit in linear format. Thus, 
little recursive re-prediction is needed. 

This RECURSIVERE-PREDICTOR is the current pretty-print 
algorithm in use. Empirical observations indicate that it is only 
some four to five times slower than PRINT. Thus, it is of practical 
use* The next section describes an algorithm that is theoretically 
linear in the size of the list. Tt has net yet been implemented, 
and, in practice, may not be worth implementing. The use of tables 
and numerical operations is required. The overhead of these 
computations might be prohibitive for handling the average LISP 



expression. Alec, such numerical operations are more efficient 
hand-coded in LAP than written directly in I.TSP. In any care, the 
final verdict must await implementation. 

F. IKE. TAELE ALCORITF, A FOTTCM-UP APPROACH 

A bottom-up attack can yield a predictor which is linear in 
the size of the tree. One prediction pass if used. The trick will 
te to remember more than Just the minimal width and corresponding 
length. Instead, a step function must be fcuilt for each node which 
provides the minimal number of lines resultirg fcr different widths. 
For example, 

(PLUS 2 ? 4) 

WIDTH # OF LIKES FORMAT 

0-4 impossible 

5-7 4 riser 

8-11 3 standard 

12-UNEtfIDTU 1 linear 

Such tables are finite. The mister of intervals is limited by the 
finiteness of LIHEWIDTH. The tables for all of the daughters of a 
given node determine the table for the parent. Fefore giving nsore 
details of this table scheme, notice that the cost is only a linear 
increase in the tasic "tree traversal" computation. [This assumes 
that the cost of numerical CCKPARE's needed to merge tables is 
roughly comparable to moving up and down levels in the tree. 3 

The table for the ;parent is built by merging the tables for 
the daughters, creating their "refinement". For example, the table 
for (PLUS 2 * 4) given above is built fron the tables for the atcras 
PLUS, "2", "3" and "4". For each possible width, the table entry is 
the minimum number of lines to pretty-print the given subtree. This 
is determined by checking the nur.ber of lines rerulting from each 
format. The numter of lines to print a given tree in a given format 
is completely determined by the choice of format and the tables for 
the daughters. A given initial width and a given format imply a 
specific width fcr each daughter. The predictor, then, looks up the 
number of lines that the daughter requires for that width. The 
total number of lines is obtained by summing over all the daughters. 

The format used to obtain the minimum number of lines is 
recorded as well. Ultimately, this bottom-up approach yields a 
table for the toplevel list. The entry for the total LIKEWIFTH 
gives the number of lines to print the expression as well as the 
program for doing it. 



Some caving In cent is possible. This csn be dene ty 
determining limits fcr the width? that a river table met corsider. 
The maxitum width is: 

LINEVIDTH - DEPTH. 

This is true since each level of the tree costs at least one unit of 
width in order to print the opening parenthesis. Alternatively, it 
can te viewed as the width corresponding to using only Eiser format. 
A lower "bound on the table is obtained by considering the use of 
only standard fornat. This results in maxiral indentation. For 
each use of standard format, the available width decreases by 

1 ;for the opening- parenthesis 

+ FLAT i where FLAT equals the linear width of the first element 

+ 1 ;for the space between the first and second elements. 

These upper and lower bounds are computed as the predictor travels 
down the tree. The tables are computed on the return trip back up. 
Thus no extra tree traversing is necessary. An additional bound on 
the minimum width that need be considered for a given table is 
obtained by the left-to-right analysis of the daughters of each 
node. Suppose the table for daughter(1) asserts that it is 
impossible to pretty-print this subtree in less width than MIN. 
Then, it is unnecessary to consider widths less than MIN for the 
remaining daughters. 

However, it is clear that such savings, though useful from a 
practical standpoint, still leave the algorithm linear in the size 
of the tree. Indeed, the table algorithm is essentially irinimal in 
its cost. This can te illustrated by a worst case analysis. 
Suppose that an intermediate width V in a table for the sublist L is 
rot computed. Obtaining the minimum number of lines can be made to 
hinge on just this piece of information. A sketch of the argument 
is: 

Construct a supertree for L for which a sequence of miser- 
standard choices could be made resulting in vidth W being 
possible. 

Construct the sisters of L such that they pretty-print 
optimally in this width. 

Then, if L behaves well for width W, it should be chesen. 
But if the number of lines to print L in width W is large, 
then it is not worth choosing. 

Hence, the choice of format depends on hew L behaves in this 
vidth. 



C. SFM ANTICS 

So for, we have introduced only three formats for lifts: 

standard forest 
miser format 
linear format 

Knowledge of the semantics of various types of ©-expressions 3ea<ls 
to additional forms. For example, argument lists for PRCG's and 
LAMBDA's are preferably presented as blocks, 

(PROG (***** ***** ***** ***** 
*»*»■* ***** ***** *****) 

TAG ;tapr are unindented. 

Similarly, the preferred format for SETO should be: 

(SETQ NAKBM) <PRETTY-PRINT OF VALUE(1)> 
NAHE(2) <PRETTY-PRIKT CF VALUE(2)> 

* 

. ) 

This additional versatility can be achi eved ty extending the pretty- 
print algorithm. In the current PRETTY-PRINT package, special 
formats have been designed for many LISP primitives. [This includes 
informing the predictor of the special way such functions as PROC 
and SETQ are handled-] If sufficient space is available, these 
formats are preferred over standard or miser format. See section 
III for details, 

H. COMfENTS 

The importance of documenting code cannot be under- 
estimated. Fence, the pretty-printer, when applied to files, 
formats semi-cclcn comments. These consents can be inserted in the 
code or printed on the right-hand half of the pege. Again see 
section III for details* 

I. HISTORY 

Fill Gosper developed one of the earliest pretty-print 
algorithms for LISP. It used the recursive re-prediction scheme to 
minioize the number of lines. Eugene Chamiak modified the program 
to process semi-colon comments. Ira Goldstein extended the comment 
formats, made the pretty-printer programmable with respect to adding 



rew formats for rp^cial functionr, addod a hash rcher.e fcr linear 
width and developed the table alrorithm discussed above* Carl 
Hewitt, Cuy Steele, John White, Gerry Surrican, Terry Vincpr&d, Eruci 
Roberts, and Stavros Kacrakir provided nany helpftil fuprestions. 



IH* Documentation 

The new rrind fackafje differs frorr earlier ones in providing 
a larger number of foriratn in which F-exprerrrionr and consents con 
te ground* A variety of predefined foritatr exist which can l*e 
associated with any LISP function. For unusual formats, the user 
can design his own procedures to control rrindinr- 

The fTind package is automatically leaded into TJSP upon 
executing GRIND or CRINDFF. Alternatively, the user can obtain the 
file via: . 

(FASLOAD F GRIND COM) 

The REM feature can subsequently te used to eliminate unwanted code 
(see section A-4). Send ruryestionc and tups to IRA. 

A. Top level functions 

1 . GRIND and CRINEO - f exprs 

GRIND and GRINDO convert files to pretty-printed form. Their 
input format is that of the LISP file maripulatirg functions like 
UREAD and UWRITE. 

(GRIND <filename1> <filenaine2> <device> <unarae>) 

UFILF's a pretty-printed form of the file under the same name. The 
usual LISP conventions for defeult device, user end file names are 
used. To avoid possibl e di sasters, use ">" as your recond file 
name. GRINDO does not UTILE. Hence, it is useful for filing the 
pretty-printed file under a different name. For example, 

(GRINDC GFO > DSK IRA) (UTILE CEO PRINT) 

results in the pretty-printed version bednp filed ss GEO PRINT. 

2. GRINDEF - fexpr 

GRINDEF takes atoms as arguments. It then pretty-prints 
their EXPR, FEXPR, MACRO and VALUE properties. For example, 

(GRINDEF PROGRAM PRCCRAK2) 

pretty-prints these two LISP functions. 

The defeult properties pretty-printed by GRINDEF can be 
modified in two vays. 



(CRINDEF OUST OF ADDITIONAL PROPEFTIF£> <ATO!'1> <ATOIO ...) 

appends the additional propertier to the list of default properties 
for the duration of the current call to GRINrFF. A permanent change 
to the default propertier pretty-rrinted by CRiriTFF is rcrde by 
setting the atom "GRINDPROPEETIES" to a new list of proper ti en. 

"(GRIftDEF)" will repeat the last call to GRIKDEF. IMs 
saves typing when repeatedly CRIKDEF'ing the name furctiens. 

3. Formatting 

The pretty-printer can "be programed in the following ways; 

a. (<grird-control-fn> <argumentc>) executes the grird-ccntrcl- 
fn on the given arguments. A typical grind control function is 
FROCEAMSPACE. (FROGRAKSTACE 80) sets the width available for 
pretty-printing code to 80. Comrlete documentation follows in 
III-C. 

b. (<GRIKDFN or GRINDMACRO <function> <grind-format>) assigns 
the grind-foixat to the function as either a CRINDFN or 
GRIKI'MACRC. Whenever the pretty-printer encounters the function 
as the first element of a list, the list is printed using the 
special format. The grind-format can either be the name of a 
function of no inputs or the body of a lambda definition. A 
variety of predefined formats such as PROG-FORM are described in 
the next section. ThG mechanism for building nev formats is 
presented in section III-E. 

c. (UNFCRMAT <functicn>) removes any special CRINDFN or 
GRIIiCMACRO properties of the function. 

For all of the above sj^cifications, <furctien> can be replaced by 
<list of function5>. The grind specification is then applied to 
each function in the list. 

Typically, format statements are either placed in a "GRIND 
(IHIT)" file read by the grind package when loaded; or inserted 
directly into the user's file as 



7 7 



iGRIKDFN THPROG FfiCG-FCRK) (PROCRAKSPACE 80) <cr>. 



Comments beginning with ";;*" cause the pretty-printer to evaluate 
the remainder of the line. If the line consists of only a single t 
expression, the toplevel parentheses are optional. 

;;*GRINDFN TCPROG PRCC-FCRM 

The normal LISP READ-EVAL-PRIUT loop igncres semi-colon comments. 
Hence, ;;* comments cnly have effect when the file is ground. 



4. RFKGRIHD - fexpr 

(REKGRIWP) removes all of the grind racket's functions frors 
a user's LISP. Alternatively, the user can te more selective in 
pruning the space occupied by the grind package by erasirg only 
those features he doer not need. This is done as follows: 

(REKGRIND FILE)- erases GRIND and GRINDO. Useful when only 
GRIMDEF is needed. 

(REMCRIND UCCIJTRCL) - erases the fonr*tting functions. It 
does not erase those special f wrote already defined by the 
user* But it prevents him from defining any more. Useful 
after the user has created his special formats. 

(REKGRIND FORMAT) - eraser both the formatting functions as 
veil as any all special formats. 

(REMGRIHD SEMI) - erases special functions for handling 
semi-colon cccmerts. 

5* Functions, atoms and properties reserved by grind. 

The functions and atoms reserved by grind can be found in 
the DECLARE statement in the grind file. The grind package also 
uses the indicators "GRIHDFN" and "GRINDHACRC" for specifying 
special grind formats. 

E. Predefined formats 

1« Standard formats 

The following formats are used by the pretty-printer in the 
absence cf any special formatting instructions. Choice depends on 
the available width and the cost in number of lines. The algorithm 
is described in section II. 

a. LIKEAR-FORM - The expression is printed v/ith no extra insertion 
of carriage-returns and spaces, this is the format used by the LISP 
printing primitives. It is used by GRIND only when there is 
sufficient width remaining on the line. 

t. STANDARD-FORM - This is the preferred format for lirts beginning 
with atomic functions. It is also used on other lists if fever 
lines are needed to print the code this way. 

(<function> <pretty-print of arg{1}> 
<pretty-print of arg(2)> 



<rretty-rrint of arf(?)>) 



c. MISER-FORM - This forirat conserve^ the Fj^ce reraininf on the 
line. When in width trouble, furcticn lifts are printed this way 



(<pretty-prirt of element M}> 
<pretty-print of eleirent(?)> 

• 

* 
<pretty-prirt of eleirent(n)>) 

d. FUKNY-FORH - Cccasionaly, this format decreases the number of 
lines needed to print an expression. It is used whenever this is 
the case. If PREDICT is NIL, computation is saved by ignoring it. 

(<EXEHEKT(1)> <SLEKENT(2)> ... <rRFTTY-PRICT OF rLFHEKT(N)>) 

■ 

2. Special CRINDFKs 

Each of the following frind-formats can be assipn e <3 to ar Y 
function by: 

(CRINEFN <function> <£rind-fcraat» 

a* ELOCK-FORK - the entire expression is pround as f ext where the 
left rcarfin follows the opening parenthesis of the expression. For 
example , 

(ABCDEFG 
H I J K L M N 

OPORSTU 

v n y z) 

Typically, arrument lists and planner jsitterrs are ground as blocks- 

b. DEF-FORM - Def-foro is the standard fcrnat for rrindin£ 
definitions. The "defun 11 , function-name, indicators and vguaeut 
list are always pround on the first line. The arp-urent list is 
cround as a block. The remaining elements of the definition are 
ground as a "body", i. e. depending en their size, they are fround 
one under the other in : 

i. either the space renaininp on the line, e. p. 

(DEFUK FKNAKE <ARCLIST CRCUHD AS FLCCK> ****** 

****** 



***f * . 



)- 



ii. in standard format, i. e. alirn^d um'er the function 
name: 

(DEFUN FKNAHE INDICATOR <ARCLIST GROUND AS PI*>CK> 

JHH HHH * 

iii. or in miser format, i. e. alifm^d urder the defun: 

(DEFUN FWNAHE INDICATOR <ARCIJST CROUKD AS PIOCK> 
****** 

****** 

***-***) 



c, LAMBDA-FORK - the LAMBDA and its arplirt pre rround on the first 
line. The arglist is pround as a block. The rera^ning elements of 
the LAMBDA are ground as a "tody* i. e. depending on their size, and 
in order of preference,: 

i* in either the sjace repairing on the line, e* p. 

(LATIFDA <ARGLIST GROUND AS EIOCK> ****** 

****** 
****** } 

ii. in standard format: 

(LAKFDA <ARGLIST GROUND AS ELOCK> 

JHHHHHHHHHHI 
*** * *** mm xn \ 

iii. or in miser format: 

(LAMBDA <ARGLIST CROUKD AS BLOCK> 



f***** 



) 



d. PROG-FORM - This format u?ed for FROC's if* similar to LAMBDA- 
FORM, except that taps are unindebted. 

♦ 

e. MEK-FORM - The first argument is ground as code. The remainder 
are also ground as cede unless quoted, in which case, they are 
pround as a fclock. For example. 



(fEMFFR X. 

(A E C D E T G P I J K I 
MNOPQRSTUVVX 

Y Z)) 

Py default, MEMO. MEMBER, the HAT functions, and the ASSCC functions 
are ground in this format. 

f. COMMEKT-PDRM - The CDR of the expression is /round as a Woe]:. 
For example, 

(COMMENT THIS IS A VERY LONG 
COMMENT THAT TAKES 
SEVERAL LINES) 

COMMENT, REMOE and *FEXPR, *EXFR, "LFXFR, ••ARRAY, SPECIAL and 
UKSPFCIAL clauses of DECLARE's are ground in this format. 

£- SETO-FORM - Space permitting, variables and values are ground as 
pairs. For example, 

(SETC A (PLUS 1 1) 
BO) 

If there is insufficient space, standard or miser format is used. 

'- Irvertin^ read macros 

CUCTF-type read macros can be inverted when pretty-printed. 

reader grind 
<char> <expr> > (function <expr>) > <char> <expr> 

This is accomplished via the READKACEO instruction: 

(READMACRO <function> <macro character or cheracters>) 

The macro character is PRINC'ed and then the <expr> is pretty- 
printed. Two examples are: 

(READMACRO QUOTE /') 5- (REACKACRO THV /$/?) 

<• System packages 

A package of special formats currently exirts for MICRO- 
FLNR* To utilize them t place either (PLKR) in ycur GRIKD (IKIT) 



file or ;;«FLER directly in ycur Eucro-plrr filer. 



C» Ccirjaerts 



£eni-colon ccmmerts are defined as a sentf -colon folloved by 
text and concluded by a carriole return. There comments can be 
inserted anyvhere in an s— expresrion or appear alone at the top 
level. They are completely irnored by the LTEP reader. The rrind 
package pretty-prints these comments in several forinets depending on 
whether the comment begins with 1 f 2 or 7 rerci-cclonr, 

1. Single semi's 

Comments beginning with a sirfle scrd-colon are printed to 
the right of the code. Sequencer of sin^le-seci's are merped. The 
code is normally ground in the first 70 rpaces of the line 
(PROCRAMSPACE) while the single semi's are pround in the final 49 
spaces (COMSFACE). CAP = 1 is the sysce between code and consents. 



-procraarp&ce — £ap — comerac*. 

70 1 49 



-pagevidth = 120- 



Th se values can be altered, for example, by inserting the following 
coiment intr a file: 

;;*(PAGEUIDTH 120 89 1 30) 

This results in PROCRAMSPACE beccEinf 89 t CAP 1 and COKSPACE 30. 

Eor cede that contains no single semi's, a PROCRAMSPACE of 
SO. is preferable. 

■ 

2. Double seci's 

These comments are printed as part of the code with the 
proper indentation. Sequences of double semi 's ere raerped. at the 
top level, TOPVIDTH = PAGFV/IDTH is used. Inside code, dcuble seci's 
are lioited to PRCGRAHSPACE. To alter TOPWIDTK, execute: 

(TOPUIDTH <nevvalue>) 

3- Triple semi's 

";;;*.*" are similar to • 1 ;;..." vith respect to indentation, 
However, they are otherwise rot nodified by frinc. Spaces are not 
filled and sequences of comments are never rcerred. They are thus 
useful when the user desires his comment to be printed exactly as 



cr * pi nally tyred . 

D. Grind control 

Th^se functions ret various rwitches and variables for the 
pretty-printer. 

T* FILL causes multiple sfeces afpearinp in rinple ard double semi's 
to be merped. Periods endinp sentences are followed by two spaces. 
This is the default case. 

2. NOFILL causes multiple sreces to be treated ar such. Triple 
semi's are always NOFILL'ed. 

3. MERGE causes double semi's to be merged, if sufficient COKSPACE 
regains on the line. 

4. NOI*!ERGE causes double semi's not to be merged. This is the 
rarmer in which triple serci's are handled. The full papewidth is 
used. 

5- PACE causes the output of a formfeed. 

6. TF caures grind to insert formfeeds approximately every 60 lines. 
Formfeeds are only inserted at the toplevel t never appearing within 
s-expressions. This is the default case. 

7- NCFF limits the insertion of formfeeds to explicit calls of PAGE, 

8. FFACE causes prind to preserve original jsging of user's file, 

9- NOPREDTCT - This switch makes the grind dumber but faster. The 
algorithm no longer consider as many alternatives for grindinr each 
expression. For PROG-FORM and DFF-FCRK, format 1 is no longer 
considered. Similarly, TUNNY-FORMAT is never considered. Dunb mode 
is the default state* 

10. PREDICT - All of the forests discussed in the previous pages are 
considered. 

11. FAGEWIDTH <pagevidth> <prograES£«ce> <gap> <coiranentspace> 

12. FROGRAKSPACE <value> - resets the value of the PRCCRAMSPACF. - 
Enlarging PRCGRAKSPACF shrinks COMSPACF. 

13* COMSFACE <value> resets the width used fcr single semi comments. 
The tradeoff is again with the PRCGRAKSPACF. 

14. TOPWIDTK <value> - resets the width used for toplevel double 
semi consents. 



E. Definite n« w formats 

The user may wish to po beyond the predefined format? 
discussed in section III-E. To do this, CRIKDFN can be used to 
define special /rind functions [CCF's] of hip own design. The 
syntax is as follows: 

(GRINBFN <atom or list of atoms> <rrind-fonnat>) 

where the definition If either the name of O-input procedure or the 
body of a LAMBDA expression. 

GRIHDFNs are processed as follows: assume the atom LI has a 
SGF associated with it- Then, whenever expressions cf the form (L1 
... T LH) are encountered, rrird prints "(" and then transfers control 
to the definition of the SGF. Uron entering the SGF, the following 
free variables are relevant: 

L < (L1 ... LH) 

K < CKRCT = remaining line width, following the "(". 

A 93F generally processes some initial segment of L, CDR'ing 
L in the process. Note that the SGF must at least process L1- Upon 
completion, if L has been set to NIL, grind simply prints the 
closing parenthesis ") a - If, on the other hand, L has been rebound 
to scire terminal segment cf itself, 

L = (Li ... Ln) 

then grind prints the remainder of L as the body of a DEF-FCRM, i. 
e. the elements cf L are printed one under the other in either 

a. the space reinaining on the line 

b. aligned under L2 
or c. aligned under L1. 

2. Vocabulary 

The following vocabulary is useful for defining SCF's: 

1* (KEHSEKI) - expr - This function processes any ; comments that 
occur as initial elements of L, CDR'ing L in the process. 

2. (FPRIH S F) - expr - S is printed in the format specified by F 
where F can be: 

'LIME - equivalent to PRIK1 
'BLOCK - ELOCK-FCRH 



'LIST - CCKKHIMCRM 

'CO' E - anHies pretty-printer tc S. 

FPRIH should not be riven ; comments as input. {REKEBil) is 
generally used to avoid this- PTKIM does not print a spece 
following S. 

?. (FORM F) - expr - Thir furction is deripned to relieve the user 
of an explicit concern for ccmmerts. It also frees him from 
printing spaces between elements of L. Its defiriticn is; 

'REMSEHI) 
FFRIN (CAR L) F) 
!AND (SETO L (CDR L)) (PRIMC 7 )) 

Its action is to first apply EEKEEMI, removing any initial comments 
from L* It then pretty-print? (CAR L) in the specified format F. 
Finally it CDR's L and prints a space if there ir still ttore to go. 

4. (TURFRI) - expr - A carriage return is printed- TERPRI should 
not te used. 

5. (INDENT-TC N) - expr - This function causes CHRCT to be set to N 
ty printing a carriage return if necessary (K > CHRCT) and spices. 
Note that CHRCT is the current width. This number is equal to the 
indentation subtracted fro© the total line width. A conmon bug is 
to treat M as the indentation. 

6. (INDENT H) - expr - H spaces are printed. An error results if H 
exceeds the spsce renaining en the lire. 

7. (FOFL) - expr - L is set to (CDR 1). Then REKSEHI is applied. 
The net result is to CDR L until its CAR is not a comment. 

8 a. (TESTL) - lexpr ~ returns the first element of L that IS NOT 

a ";" comment. 
b. (TESTL j) returns the jth element of L that is rot a comment* 
c- (TESTL 3 t) returns the entire remainder of L beginning WITE 

the ^th element. 

9- (SEMI? K) - expr - returns T only if K is a semi-colon comment. 

3- EXAMPLES 

Following are some examples of SGF's- LAMBDA'S are ground 
fcy default in DEF-FCRM. The user could achieve the sense effect by 
defining the following SGF: 

1 (GRINDFN LAHBDA (TORM 'LINE) 

2 (lORM 'BLCCK)) 



(FCRK 'LINE) in line 1 print? LAKFDA end repp L. (FORM 'FLOCK) in 
line 2 prints the arpunent list cf the LPKFDfi in BLOCK-FCRM end 
apain pops L. Control is then returned to prind and the remainder 
cf the LAMBDA is printed as a body. 

Another exacple B ipht be where the urer wishes to prind all 
expressions of the form: 

(DEFPF.OP <ATOH> <DEFIKITICK> <FXFR, FFXFR CR f'ACRO) 

as DEFUK's. This would be done by: 

1 (CRIHEFH DEFPROP 

2 (COflD (fMFMQ (TEETL 4) '(FXPR FEXPR MACRO)) 

3 (SETC L 

4 (APPEND (LIST 'DFFUN (TFSTL 2)) 

5 (COKD «F0 (TFSTL 4) 'EXPR) 

6 NIL) 

7 ((LIST (TESTL 4)))) 

8 (CDR (TFSTL 3)))) 

9 (BEF-TORH)) 

10 ((FORM LINF)))) 

The KEHQ of line 2 checks for whether the indicator is a function 
property. If so, L is redefined as the appropriate EEFUK: 

(CADR L) = function name 

The cond cf line 5 puts fexpr/macro into the EEFUK 
(CDR (CADDR L)) is the arpuinent list of the function 
(CDDR (CADDR I)) is the body of the function 

and then pround in DFF-FCRM. If not, DEFPRCP is printed and control 
is returned to prind. 

■ 

Finally, consider a function called CMEAKS whose arguments 
are property lists. It is to be pround as follows: 

(CMEANS 

(<IND-11> <GRIND PR0P-11> 

<IKD-1N>~<CRIBD PK0P-1K>) 

(<IHD-K1> <CRTKD PR0P-K1> 

<IND-HH>*<GRIKD FPOP-KK>)) 

Suppose the additional subtlety is desired that properties with 
indicator FCO are pround as blocks while ell other properties are 
pround ordinarily as code. The followinp SCF achieves this format. 



(CRIKDFN CHE A1IS (PRCG NIL 

FORM 'LIKE) 

SETO N (*D7F U 4.)) 

REMSENI ) 

(LAMBDA (L) 

5 (PROG NIL 

6 (INDEKT-TC (/DD1 H)) 

7 (PRINC '/() 

8 B (EEMSFMI) 

9 (INDENT-TO N) 

10 (COKr ((FO (CAR I) 'FCC) 

11 (FORM 'LIKE) 

12 (FORM 'BLOCK)) 

13 ((FORM 'LINF) 

14 (FORM 'CODE))) 

15 (AND (TESTL) (GO P)j 

16 (PRINC '/)) 

17 (REHSEMI))) 

18 (CAR LI) 

19 (COHD ((POEL) (CO A))))) 

Line 1 prints "CUBANS". Line 2 establishes the indentation of the 
arguments of CMEAES. Line 3 processes any comments preceding the 
first argumert. Line 4 "binds the srecial free variable L to the 
current argument of CMBAKS for use by FORM and REM. Line 6 indents 
for the current argument. Line 8 processes any initial comments 
embedded in the argument. The ccnd of line 10 forks depending on 
whether or not the indicator is "FOO". In line 15, TESTL returns 
NIL if I contains no more indicator- property pairs. Line 16 prints 
the closing parenthesis. 17 processes any remaining comments. Py 
line 19. the current argument of CMEANS has been ground. Hence, L 
is popped. If there are no more arguments, POP! returns NIL and the 
SGF is done. 

4. GRINDMACROs 

A GRIKDMACRO differs from the above grind functions in that 
the grind package takes nothing for granted. It does not 
automatically print the opening rarentherir, the bolance of I and 
the closing parenthesis. If the GRINDMACRO function returns T, then 
the pretty-printer does nothing more on L. The assumption is that 
the GRIKDMACRO has done all the work. This would be the case for a 
GRINDMACRC for "QUOTE": 

(GRINDMACRO QUOTE (PRINC */') 

(PPRIN (CADR L) 'CODE) 
T) 



Alternatively, if the CRTRDMACRO returnr MIL, the pretty-printer 
prints L as thourh ncthirr had harpered. This mode is irefu 1 for r 
GRirmHACRC uped to print "index" infcmstion he coiwentr, rrer^riin^ 
the s-expresrion. - 

CRIHDKACRCs can te defined similarly to CRINEFHs. 

(GRIIJDKACRO <ATOI-' or LIST OF ATOKS> <rrir ; d-fcraat>) 

Apain the definition can be either the fccdy of a LAf'FDA or a 
function of inputs. 



VI- Fossitle future improvements 

A. CCNCETTUAL 

1* The lanpua^e for specify inf fcnratr should he expanded. A 
pattern-crierted or template approach Kifht be preferable. 

2. The table schene would allow the rretty-printer to consider 
indentations for the ar^ueicentE cf a functior* intermediate between 
miser and standard format. The elporitlw; could choore the greatest 
indentation that doer not cause extra lire? to "be printed. 

3. Pretty-printers could do more than just insert spaces and 
carriage returns* For example, FACTORIAL could Ve printed as 
follows: 

(DEFUN FACTORIAL (X) (COKD ((= X 0) 1) (=>))) 

<* (FACTORIAL (1- X)) X) 

• f =>" is interpreted by the reader to ne&n that the next expression 
READ should be inserted here. This suggestion is due to KIHSKY- 

4* The fact that comments are not read in as part of the list 
structure presents a serious obstacle to interactive debugging. The 
user must return to a text editing language to cake corrections in 
his code* Otherwise, he loses ary commentary. One possible 
solution would be for comments to be resident. Paring could be used 
to store all concerts en the pane rare* This would allow their to be 
swapped out during runtime* The evaluator would have to be codified 
to ignore pointers to a comment page. These codifications are 
protebly veil worth the effort* The user would be able to prove 
continuously between defining, running* &Ttd editing programs* 

E- ir-TLEMKTATIOM 

1- Grind should accept a wider variety of TJ6*like specifications* 

for example. 

;*DASH > Line of dashes 

;*CENTER <text> > Centers text in comment 

2* The current scheme for ; comments leads to enormous list 
structures since every comment is expanded to a list* one letter per 
node- Alternatives to this approach are: 
A. TYI rather than readch. 

E* Pack ascii characters into jTiemes or array* 
C* Use read to peck by turning off syntax of parentheses. 
Periods* coonas. 



Z. GRIND rhould use ite own cbarray end rcndtable to irniinize 
interference with the user s world. 

4. Special grind formats can check fcr the correct nwtber of inputs. 
3- Crind could print pope nur.bers 

6. The grind file should be broken into 2 files, the first contains 
the basic grind. The second contains the fns for the user tc define 
his own formats. This decreases the initial load on free stcrare 
when reading in the tasic grind. 

7. Special fornats should be created for DO, CNVF, and LAP code. 



